Skip to content

Android: clear a backoff wait when the app starts, resumes or comes to the front - #88

Open
dmurphy5 wants to merge 10 commits into
dylan/android-stop-not-failurefrom
dylan/android-clear-wait
Open

dmurphy5 wants to merge 10 commits into
dylan/android-stop-not-failurefrom
dylan/android-clear-wait

Conversation

@dmurphy5

@dmurphy5 dmurphy5 commented Nov 18, 2026 •

Copy link
Copy Markdown

Android: clear a backoff wait when the app starts, resumes or comes to the front

What was wrong

After a long offline time, every Android upload can wait up to 2 hours for its retry backoff (nextAttemptAt). Opening the app did not wake it. The boot sweep kept the far wake, resume() kept it too, and nothing listened for the app coming to the foreground.

Second problem, from the branch below: after a system stop, WorkManager keeps the stopped row ENQUEUED and makes it wait min(30 s × 2^(n−1), 5 h) from its last enqueue time. While that row waited, schedule() added no row, so the entry fell back to WorkManager's wait. Nothing in the library could start it sooner.

What changes

  • Which waits are cleared. The boot sweep, resume() and a return to the foreground end a wait only when both of these hold:

    • the failure behind it had no server response, or an older version saved the entry;
    • the failure was 30 s or more ago.

    A wait after a server response keeps its time, because the server asked for it, and ending it early would spend a transient rule's retries faster. Each entry now saves waitCause and failedAt. Entries from older versions read as unknown. After a clear, and after resume(), the streak is at most 5.

  • Pause. pause() now keeps the wait and its cause. resume() gives back what is left of it, and ends it only under the rule above. A kept wait keeps its streak. A paused row does not show nextAttemptAt.

  • The foreground. onHostResume fires on every Activity resume, so retryNow runs at most once per 30 s, on the queue executor. The 30 s is measured with SystemClock.elapsedRealtime, so setting the wall clock back cannot stop it.

  • A row that can start. For every queued entry with no wait, schedule() replaces a main-chain row that WorkManager holds back, unless a row of the main chain is running. The rule counts a row due within 30 s as starting now. A RUNNING row counts as covered only when a BLOCKED row follows it. scheduleRun makes the main row before it cancels the old wake. Before it cancels, it reads the stored entry again and keeps a wake that a long wait still needs. A foreground also makes the wake again (KEEP) for a waiting entry that has no delayed wake row, also when a held-back main row exists.

  • Robustness. retryNow goes on past an entry that fails to save or schedule, emits what it saved, and writes one error. When only its clear fails to save, the sweep schedules the entry as it found it.

  • 15-minute cap. It applies only to a call whose every try failed while it connected. The exception must be one of ConnectException, UnknownHostException, NoRouteToHostException, PortUnreachableException, SSLHandshakeException or SSLPeerUnverifiedException. OkHttp 4.12.0 attaches a call's earlier tries as suppressed exceptions, and each of those must be one of the same classes, as when every address of a host refuses. Timeouts keep maxMs, because a connect timeout and a read timeout throw the same class.

  • Chunked parts. The part that releases a run takes the stored streak with its own count (backoffPartStart). It goes on from that streak in the next run, and only its own acceptance resets it. The other parts count from 0.

  • After a time-limit stop, the fresh wake is added only when WorkManager holds the stopped row back. Otherwise one entry would have two rows.

Behavior change

On Android, some backoff waits now end when the app starts, resumes or comes to the front. These are waits after a failure with no server response, at least 30 s old. A connect-phase failure waits at most 15 minutes. Details are in CHANGELOG.md (Unreleased) and the README ("Backoff and the app").

WorkManager 2.12.0, confirmed with javap and the WorkInfo docs:

  • A stop sets the row back to ENQUEUED and keeps runAttemptCount and lastEnqueueTime.
  • A backed-off row starts at lastEnqueueTime + min(30 s·2^(n−1), 5 h) and not before.
  • nextScheduleTimeMillis uses the same formula.

Tests

  • Scheduling against a fake WorkManager (MainChainTest): the rules run against a fake that follows WorkManager 2.12.0. It covers the reviewer's probes P3 and P5, the step table, the 30 s margin, and the cost per foreground.
  • Probe regressions:
    • P1: a 503 wait survives all three triggers.
    • P2: foregrounds do not spend a rule's maxRetries.
    • P4: retryNow goes on past a failed scheduling call.
    • P6 and P8: a part that always fails backs off further in each run, also next to a slower part that holds a higher streak.
    • P7: a stale snapshot keeps the wake a worker made meanwhile.
    • P9: pause and resume do not spend a rule's retries.
    • P10: a connect failure after an earlier try in the same call is not capped; every refused address of a host still is.
  • The clear rule: a transport wait of 30 s or more is cleared by each trigger, a younger one is not, an old-format entry is cleared, and a sweep followed at once by a foreground clears once.
  • The cap: both sides of the 15-minute rule are tested.
  • Mutation checks: each fix was broken on purpose, and a test failed each time.
  • Checks, each with exit 0: Android unit tests (515 passed), yarn lint:ci, yarn typecheck, yarn test (305 passed), and swift test (383 run, 1 skipped, 0 failures).

Three independent review rounds were applied. Stacked on #85.

🤖 Generated with Claude Code

dmurphy5 and others added 8 commits November 17, 2026 18:01
…o the front

After a long offline time every Android upload could wait up to 2 hours,
and opening the app did not wake it. The library now clears that wait by
itself.

- QueueController.retryNow(keys?): a queued entry that waits for a backoff
  runs now and keeps at most 5 backoff steps. A queued entry with no wait
  is scheduled when no row of it can start now (one WorkManager query).
  The boot sweep and resume() do the same; a return to the foreground
  calls retryNow on the queue executor.
- resume() starts the backoff of a resumed entry over.
- schedule() replaces a main-chain row that WorkManager holds back after
  a system stop, when no run of the entry is in progress. Before, it added
  no row, and the entry waited for WorkManager's own backoff (up to 5 h).
- A chunked part uses the stored streak only until a part is accepted in
  the run.
- A transport failure waits at most 15 minutes.
- After a time-limit stop, no fresh wake row when WorkManager starts the
  stopped row again at once, so the entry does not get two rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CHANGELOG (Unreleased): the behavior change for the boot sweep, resume()
and a return to the foreground; the replaced WorkManager row; the 15-minute
cap for a transport failure; the chunked streak base; and the fresh row
after a time-limit stop that is now added only when WorkManager holds the
stopped row back. README: "Backoff and the app" under the Android notes,
resume() on Android, and the transport cap in the retry table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the review findings

From the review of this branch:

- A wait is cleared (boot sweep, resume(), foreground) only when its
  failure had no server response, or an older version saved the entry,
  and 30 s or more after that failure. A wait after an HTTP response keeps
  its time, so foregrounds cannot spend a transient rule's retries or send
  back to back. New persisted fields: waitCause, failedAt. resume() keeps
  at most 5 steps instead of 0.
- scheduleRun makes the main row before it cancels the stale wake.
- retryNow goes on past an entry whose save or scheduling fails, emits
  what it saved, and writes one error.
- A held-back main row is replaced also while a wake worker runs; only a
  BLOCKED row or one that starts now counts as the row after a run.
- The sweep schedules an entry as found when only its clear fails to save.
- The start margin is 30 s.
- Only connect-phase failures (ConnectException, UnknownHostException,
  NoRouteToHostException, PortUnreachableException, SSLHandshakeException,
  SSLPeerUnverifiedException) cap the wait at 15 minutes.
- A chunked part that set the stored streak goes on from it, and only its
  own acceptance resets it (new persisted field backoffPartStart).
- The foreground retryNow runs at most once per 30 s, and the library
  query filters states in WorkManager.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CHANGELOG (Unreleased) and README: a wait is cleared only after a failure
with no server response (or an older entry) and 30 s or more after it; a
wait after a server response keeps its time; a return to the foreground is
every Activity resume, limited to once per 30 s; the next wait after a
clear is 32 times baseMs; the 15-minute cap covers connect-phase failures
only; the chunked part rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e wait

From the delta review of this branch:

- cancelStaleWake reads the stored entry again and keeps a wake for a
  queued entry whose wait is still longer than a worker sleeps out. A
  stale snapshot could cancel the wake a worker made meanwhile (P7). A
  return to the foreground also makes the wake again (KEEP) for a queued
  entry whose wait stays and that has no unfinished row. rowSummary()
  replaces startableIds(): one query gives both sets.
- The chunked part that releases a run takes the stored streak with its
  own count, so a slower part's higher streak does not hide a part that
  fails every time (P8).
- reachedNoServer also needs no suppressed exception: OkHttp attaches the
  earlier tries of a call as suppressed, and one may have sent the body
  (P10).
- The foreground throttle uses SystemClock.elapsedRealtime.
- pause() keeps the wait with its cause; resume() gives back what is left
  and ends it only under the clear rule (P9). A paused row does not show
  nextAttemptAt.
- executePart takes the part's start from the start entry, with no store
  read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… covers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmurphy5
dmurphy5 added this pull request to stack #89 November 18, 2026 00:08
@dmurphy5 dmurphy5 changed the title dylan/android clear wait Android: clear a backoff wait when the app starts, resumes or comes to the front Nov 18, 2026
dmurphy5 and others added 2 commits November 17, 2026 19:14
…de a held main row

From the third check of this branch:

- reachedNoServer accepts suppressed exceptions when each one, and each
  one nested in it, is a connect failure too: every address of a host
  refused. Any other suppressed exception still rules the cap out.
- toResumed keeps the streak when a wait is kept over the pause, and caps
  it at 5 only when the wait ended (resume() and the sweep's repair path).
- retryNow makes the wake (KEEP) for a waiting entry that has no delayed
  wake row, also when a held-back main row exists. RowSummary.withWake
  lists entries with a delayed row; only a wake has an initial delay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eside a held row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant